PenMode

PenMode
Header:	Quickdraw.h		Carbon status:	Supported

Sets the pattern mode of the graphics pen in the current graphics port.

void PenMode (
    SInt16 mode
);

Parameter descriptions

mode: The pattern mode. See “Source, Pattern, and Arithmetic Transfer Mode Constants”.

DISCUSSION

Using the pattern mode you specify in the mode parameter, the PenMode function sets the manner in which the pattern of the graphics pen is transferred onto the bitmap (or pixel map) when you draw lines or shapes in the current graphics port.

If you specify a source mode (such as one used with the CopyBits function) instead of a pattern mode, no drawing is performed.

The current pattern mode is stored in the pnMode field of the current graphics port. The initial pattern mode value is patCopy, in which the pen pattern is copied directly to the bitmap.

To use highlighting, add the hilite constant or its value to the source or pattern mode:

With highlighting, QuickDraw replaces the background color with the highlight color when your application draws or copies images between graphics ports. This has the visual effect of using a highlighting pen to select the object. (The global variable HiliteRGB is read from parameter RAM when the machine starts. Basic graphics ports use the color stored in the HiliteRGB global variable as the highlight color. Color graphics ports default to the HiliteRGB global variable, but can be overridden by the HiliteColor function.

This pen-manipulation function uses the local coordinate system of the current graphics port. Remember that each graphics port has its own pen, the state of which is stored in several fields of its GrafPort or CGrafPort structure. If you draw in one graphics port, change to another, and return to the first, the pen for the first graphics port has the same state as when you left it.

SPECIAL CONSIDERATIONS

When your application draws with a pixel pattern, Color QuickDraw ignores the pattern mode and simply transfers the pattern directly to the pixel map without regard to the foreground and background colors.

The results of inverting a pixel are predictable only with direct pixels or 1-bit pixel maps. For indexed pixels, Color QuickDraw performs the inversion on the pixel indexes, which means the results depend entirely on the contents of the color table. The eight colors used in basic QuickDraw are stored in a color table represented by the global variable QDColors. To display those eight basic QuickDraw colors on an indexed device, Color QuickDraw uses the Color Manager to obtain indexes to the colors in the CLUT that best map to the colors in the QDColors color table. Because the index, not the color value, is inverted, the results are unpredictable.

AVAILABILITY

Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.